RFC: optional repo URL and conversation/range metadata#17
RFC: optional repo URL and conversation/range metadata#17jonathansantilli wants to merge 1 commit intocursor:mainfrom
Conversation
This proposes backwards-compatible (optional) extensions and clarifications to improve interoperability across Agent Trace producers and consumers: - Add vcs.repository_url to disambiguate revision identifiers outside of repo context. - Add conversation.tool / conversation.kind / conversation.ids and range.ids to capture multi-tool provenance and per-turn/tool-call linkage. - Make tool.version optional. - Add guidance for content_hash (sha256 baseline, LF normalization, hash final recorded content), trace lifecycle (provisional vs final), git history rewrites, and privacy/durability of URLs. - Recommend well-known related.type values (e.g., transcript, prompt_artifact, diff_artifact, inference_artifact). All new fields are optional; existing records remain valid. Reference trace-store is updated to emit version 0.1.0 and populate vcs.repository_url when available.
|
Thanks for the suggestion! This is quite a large change. Let's first discuss in an issue. I think we should also consider if there are actually multiple suggestions inside of this one PR which could be broken into separate issues. Our goal is to start by keeping the spec minimal until there's more convergence with implementation partners. It would also help to add more details and background on why each of these changes should be added (which also would help with smaller pieces). |
Thanks for the review, @leerob, really appreciate the guidance. Fully agree that smaller, well-scoped issues are the right approach. We've been running Tracy in production with customers, so each of these proposals is grounded in real interoperability patterns we've encountered, happy to provide that context per issue. Quick question before I proceed: do you already have a preferred issue structure or categorization approach you'd like contributors to follow? I want to make sure each issue is easy to evaluate on its own merits. If there's no specific template, I'll create separate issues covering areas like VCS disambiguation, conversation-level metadata, range-level linkage, and spec clarifications, each with motivation, use cases, and backwards-compatibility notes. Thanks again for keeping the spec tight. Looking forward to iterating on these. |
2 participants
Summary
This PR proposes backwards-compatible (optional) extensions and clarifications to Agent Trace to improve interoperability across producers/consumers.
Context
We’re engineers at Mobb. We maintain Tracy, a VS Code/Cursor tracing implementation
We want to contribute implementation-grounded feedback so Agent Trace can represent common, high-signal attribution data (multi-tool provenance, modality, per-turn correlation) without forcing everything into vendor-specific
metadata.Scope Alignment
These changes align with Agent Trace’s goals (interoperability, granularity, extensibility, human- and agent-readable) and do not address the RFC non-goals (ownership/copyright, training data provenance, quality assessment, UI requirements).
This PR does not propose any storage requirement or capture/discovery protocol.
Proposed Changes
Schema updates (all optional; backwards-compatible)
vcs.repository_url(optional) to disambiguatevcs.revisionoutside of repo context.conversation.tool(optional override ofTraceRecord.tool)conversation.kind(optional modality string; examples includechat,tab_autocomplete,inline_edit,agent_action,human_typing)conversation.ids(optional opaque correlation IDs)range.ids(optional opaque IDs) for per-range linkage to a specific turn/tool call/message.tool.versionoptional.Spec guidance/clarifications
content_hashformat<algorithm>:<digest>with asha256baseline and LF normalization; hash the final recorded content at the recorded revision (after post-processing that’s part of the revision).vcs; final traces should includevcs.mixedis heuristic (no universal threshold) and can be detailed viametadata.related.typevalues when applicable (e.g.,transcript,prompt_artifact,tool_calls,diff_artifact,inference_artifact).conversation.urlandrelated[].Reference implementation
vcs.repository_urlfromremote.origin.urlwhen available.versionto0.1.0(previously1.0).Compatibility
All new fields are optional; existing records remain valid, and consumers can ignore unknown fields.
Feedback
We expect to see different implementations in open source. This may influence the spec in the future, and we are open to feedback.